package org.mentalsmash.crossroads.parsing;

import java.io.File;
import java.io.FileNotFoundException;
import java.io.InputStream;

import org.mentalsmash.crossroads.Crossword;

/**
 * Parser of crossword files should implement this interface.
 * @author Andrea Reale
 */
public interface CrosswordParser {
	
	/**
	 * Parse just crossword schema definition file given the references to an stream for  source files. The result of the parsing is 
	 * an instance of the Crossword class describing the parsed sources
	 * @param schema an input stream encapsulating the source for the crossword schema 
	 * @return an instance of the Crossword file, built according to the descriptions found in the crossword sources 
	 * @throws SyntacticException if there is some syntactic error in one of the source files (it would be better if the exception contains a detailed description of the error)
	 * @throws SemanticException SemanticException  if there is some semantic error in one of the source files (it would be better if the exception contains a detailed description of the error)
	 * @throws ParsingException for any other kind of exception related to the parse action.
	 */
	public Crossword parseCrosswordSchemaOnly(InputStream schema) throws SyntacticException, SemanticException, ParsingException;
	
	/**
	 * Parse both crossword schema definition file and definitions file given the references to the source files. The result of the parsing is 
	 * an instance of the Crossword class describing the parsed sources
	 * @param schema the source file describing the schema (usually has the .schema extension)
	 * @param definitions the source file containing definitions for crossword entries.
	 * @return an instance of the Crossword file, built according to the descriptions found in the crossword sources 
	 * @throws SyntacticException if there is some syntactic error in one of the source files (it would be better if the exception contains a detailed description of the error)
	 * @throws SemanticException  if there is some semantic error in one of the source files (it would be better if the exception contains a detailed description of the error)
	 * @throws FileNotFoundException if one (ore both) source file is not found or cannot be read from the file system.
	 * @throws ParsingException for any other kind of exception related to the parse action.
	 */
	public Crossword parseCrosswordSource(File schema,File definitions) throws SyntacticException,SemanticException,FileNotFoundException,ParsingException;
	
	/**
	 * Parse both crossword schema definition and definitions given a pair of strings containing the sources for both the files.
	 * Note that newline characters and indentation whitespaces in the string should be relevant. 
	 * The result of the parsing is an instance of the Crossword class describing the parsed sources
	 * @param schema a string containing the source for the crossword schema
	 * @param defintions a string containing the source for crossword's entries definitions
	 * @return an instance of the Crossword file, built according to the descriptions found in the crossword sources 
	 * @throws SyntacticException if there is some syntactic error in one of the source files (it would be better if the exception contains a detailed description of the error)
	 * @throws SemanticException SemanticException  if there is some semantic error in one of the source files (it would be better if the exception contains a detailed description of the error)
	 * @throws ParsingException for any other kind of exception related to the parse action.
	 */
	public Crossword parseCrosswordSource(String schema, String defintions)throws SyntacticException,SemanticException,ParsingException;
	
	/**
	 * Parse both crossword schema definition file and definitions file given the references to a pair of input streams for  source files. The result of the parsing is 
	 * an instance of the Crossword class describing the parsed sources
	 * @param schema an input stream encapsulating the source for the crossword schema 
	 * @param defintions an input stream encapsulating the source for the crossword defintions 
	 * @return an instance of the Crossword file, built according to the descriptions found in the crossword sources 
	 * @throws SyntacticException if there is some syntactic error in one of the source files (it would be better if the exception contains a detailed description of the error)
	 * @throws SemanticException SemanticException  if there is some semantic error in one of the source files (it would be better if the exception contains a detailed description of the error)
	 * @throws ParsingException for any other kind of exception related to the parse action.
	 */
	public Crossword parseCrosswordSource(InputStream schema, InputStream defintions) throws SyntacticException,SemanticException,ParsingException;
}
